Troubleshooting Your Database

This section provides troubleshooting information specific to the following SequeLink Servers:

"Connecting with SequeLink® Server for ODBC Socket"
"Connecting with SequeLink® Server for JDBC Socket"
"Connecting with SequeLink® Server for DB2 on z/OS"

Connecting with SequeLink^® Server for ODBC Socket

The SequeLink Server for ODBC Socket is a service that provides data access to any database that is accessible through an ODBC 2.0- or 3.0-compliant driver. Because SequeLink accesses the database by using the driver manager and the ODBC driver, this makes SequeLink Server for ODBC Socket highly dependant on the quality and behavior of the ODBC driver through which it connects. Because most drivers have their own specific behaviors, and the ODBC specification leaves room for individual interpretation, using a specific driver with SequeLink can show unexpected behavior.

This section summarizes the results that DataDirect Technologies found when testing connections with SequeLink Server for ODBC Socket to ODBC drivers. This section also describes how to determine which component is causing the problems that can occur when you are using SequeLink Server for ODBC Socket.

Using SequeLink^® Server for ODBC Socket

Configure an ODBC system data source for an ODBC 2.0 or higher driver (refer to the documentation for the driver for instructions on configuring and testing the connection to the data store).
If the driver did not come with a Driver Manager, install a Driver Manager (refer to the SequeLink Installation Guide for a description of the required Driver Manager).
Install the SequeLink Client.


On Windows: Install SequeLink Server for ODBC Socket. When prompted, supply the connection string for the data source that you created in Step 1. The connection string must have the format: DSN=odbc_system_data_source.



On UNIX and Linux: Install SequeLink Server for ODBC Socket. When prompted, supply the connection string for the data source that you created in Step 1 and the name of the library that contains the driver. Depending on the ODBC driver used, you might be prompted to set additional environment variables. For more information, refer to the SequeLink Installation Guide.

Test your SequeLink environment by establishing a connection between the SequeLink Client and the SequeLink Server.

If you installed the ODBC Client or JDBC Client, you are ready to use the SequeLink Server for ODBC Socket.

If you installed ADO Client, continue to Step 6.

Define values for the DataSourceProviderTypesFile and DataSourceProviderTypesSection service attributes. Refer to the SequeLink Installation Guide for more information.

Using the ODBC Socket Service with DataDirect Connect^® for ODBC Drivers

If you are using the SequeLink Server for ODBC Socket service with a DataDirect Connect for ODBC driver, your application can experience problems when it re-binds parameters with a different scale, precision, or sqltype. The following is an example of an error message that is generated when this situation occurs:

[DataDirect][ODBC Oracle driver]Data type for parameter 2 
has changed since first SQLExecute call. 

To avoid this problem, you can activate a workaround in the DataDirect Connect for ODBC driver. For more information about workarounds for the DataDirect Connect for ODBC driver, refer to the DataDirect Connect for ODBC Reference and README file.

NOTE: The SequeLink for ODBC Socket Server incurs a performance penalty when setting this workaround, so use this workaround only for those applications that need it.

The workaround can be activated using either of the following methods:

By changing the data source definition
By changing the value of the SequeLink DataSourceSOCODBCConnStr service attribute

Changing the Data Source Definition

When you enable the workaround in the data source definition, all connections that use the data source have the workaround activated, even if the connection request does not come from SequeLink Server for ODBC Socket. For more information about using ODBC connection strings in the data source definition, refer to the SequeLink Developer's Reference.

On UNIX: Edit your ODBC.INI or ODBC64.INI file to add the following key and value to the ODBC Data source section:

WorkArounds=536870912 

On Windows: Edit the ODBC.INI section of your registry to add the following key and value to the ODBC Data source section:

WorkArounds=536870912  

Changing the SequeLink Connection String

SequeLink Server for ODBC Socket uses a connection string to initiate a connection to an ODBC driver. You can change this connection string in the DataSourceSOCODBCConnStr service attribute, using the appropriate SequeLink administration tool for your platform. (For information about service attributes and SequeLink administration tools, refer to the SequeLink Administrator's Guide.)

The following is an example of a connection string that enables the workaround for a specific data source:

DSN='Employees'; WorkArounds=536870912 

In this example, only the SequeLink connections that specify the data source Employees have the workaround activated. By using multiple SequeLink data sources, you can control which SequeLink connections use the workaround.

Using the ODBC Socket Service with a Third-Party Driver

SequeLink Server for ODBC Socket requires a properly configured third-party ODBC driver. The ODBC driver must work correctly with the DataDirect Technologies ODBC Driver Manager and implement the ODBC functions listed in Table 2-2.

Table 2-2. Required ODBC Function Support for the Third-Party ODBC Driver

SQLAllocHandle SQLBindCol SQLBindParameter SQLBulkOperations SQLCancel SQLColAttribute SQLColumnPrivileges SQLColumns SQLDescribeParam (optional) SQLDisconnect SQLDriverConnect SQLEndTran SQLExecDirect SQLExecute

SQLFetch SQLFetchScroll (optional) SQLForeignKeys SQLFreeHandle SQLFreeStmt SQLGetConnectAttr SQLGetData SQLGetDiagRec SQLGetFunctions SQLGetInfo SQLGetTypeInfo SQLMoreResults SQLNumParams SQLNumResultCols

SQLParamData SQLPrepare SQLPrimaryKeys SQLProcedureColumns SQLProcedures SQLPutData SQLRowCount SQLSetConnectAttr SQLSetEnvAttr SQLSetStmtAttr SQLSpecialColumns SQLStatistics SQLTablePrivileges SQLTables

Using the ODBC Socket Service with IBM DB2 Driver

When you use SequeLink Server for ODBC Socket with the IBM DB2 driver, you must specify the name of the database that will be accessed through the connection. The name of the database is passed using the DBALIAS keyword.

To connect successfully to a DB2 database using SequeLink Server for ODBC Socket, you must specify a data source name and a database in the DataSourceSOCODBCConnStr service attribute, as shown in the following example:

DSN='Employees';DBALIAS='HumanResources' 

Only one database can be specified for each SequeLink data source. To access multiple databases, you must create one SequeLink data source for each database.

Analyzing Problems in the Service for ODBC Socket

This section explains how to investigate problems or unexpected behavior when using SequeLink Server for ODBC Socket.

It is important to realize that the problem or unexpected behavior could be caused by either SequeLink Server for ODBC Socket or a third-party ODBC driver. Identifying which component is generating the problem is key to solving it.

Identifying Connection Problems

It is important to know the connection string used on a SQLDriverConnect call by SequeLink to initiate the connection to the ODBC driver. When experiencing problems with establishing a connection, examine the connection string configured in DatasourceSOCODBCConnStr service attribute and check whether it is a valid connection string. Refer to the SequeLink Administrator's Guide for information about the DatasourceSOCODBCConnStr service attribute.

Testing the ODBC Driver

You can test the backend ODBC driver with the ivcheckodbc utility that is packaged with SequeLink Server for ODBC Socket. The utility is located in the installation directory:

Windows: <install_dir>/tools/ivcheckodbc.bat
UNIX and Linux: <install_dir>/tools/ivcheckodbc.sh

This script exports the environment variables needed for searching the shared libraries. On UNIX or Linux, the environment variable name depends on the UNIX system, for example, LD_LIBRARY_PATH on Solaris, and ODBCINI, which specifies the path of the UNIX ODBC configuration file.

If the script runs successfully, you can use the information that is returned to configure your SequeLink Server for ODBC Socket.

Refer to the SequeLink Administrator's Guide for more information on using the ivcheckodbc utility with SequeLink Server for ODBC Socket.

On Windows, you can test this connection string using ODBCTest (see "Troubleshooting the ODBC Client" for information about ODBCTest). Once you have validated the connection string, SequeLink Server for ODBC Socket should be able to use it to connect successfully to the database.

Identifying the Source of the Problem

To check which component is the source of the problem:

Use the ODBC driver directly. Use the connection string configured in the DataSourceSOCODBCConnStr service attribute to initiate a direct connection to the ODBC driver. You can use ODBCTest on Windows or example on UNIX or Linux to run the same operations that gave you the problem.
Use a different ODBC driver to see if the same error occurs. Try using another ODBC driver with SequeLink Server for ODBC Socket and see whether the problem still occurs.
Use ODBC Tracing to investigate problems. SequeLink Server for ODBC Socket complies with the ODBC specification. This means that you can use standard tools, such as ODBC Tracing, to analyze and investigate problems or unexpected behavior. See "Enabling ODBC Tracing on the ODBC Client" for information about enabling tracing for the driver.

ODBC tracing for the SequeLink backend ODBC driver can be enabled with the DataSourceMSSODBCLogPath attribute. For more information, refer to the SequeLink Administrator's Guide.

Using ODBC Tracing for the Backend ODBC Driver

ODBC tracing allows you to trace calls to ODBC drivers and create a log of the traces. Creating a trace log is particularly useful when you are troubleshooting an issue.

To define the log path for all ODBC calls executed by the SequeLink service, set the DataSourceSOCODBCLogPath service attribute. Refer to "DataSourceSOCODBCLogPath" in the SequeLink Administrator's Guide.

Reporting a Problem

DataDirect Technologies technical support may ask you to provide a debug log file. SequeLink Server uses the following types of debug log files:

Session debug log file contains information related to all server processing in the context of a client session. See "SequeLink® Server Session Debug Log File" for more information.
Service debug log file contains information related to service-related processing-any kind of processing that occurs outside the context of a client session. See "SequeLink® Service Debug Log File" for more information.
Server ODBC trace of the backend driver. See "Defining a Server ODBC Trace for the Backend Driver" for more information.

Connecting with SequeLink^® Server for JDBC Socket

Using SequeLink Server for JDBC Socket and a JDBC driver on the server, you can access any databases that are accessible through a JDBC 2.0- or 3.0-compliant driver. Because SequeLink accesses the database by using the JDBC driver, this makes SequeLink Server for JDBC Socket highly dependant on the quality and behavior of the JDBC driver through which it connects.

This section describes how to determine which component is causing the problems that can occur when you are using SequeLink Server for JDBC Socket.

Using SequeLink^® Server for JDBC Socket

On the SequeLink Server, create a JDBC Socket service. Create a SequeLink Server-side data source which specifies the driver name and the connection URL of the backend JDBC driver.

NOTE: When you install SequeLink Server for JDBC Socket, this configuration is done automatically.

Install the SequeLink Client.
Install SequeLink Server for JDBC Socket.
Modify the SequeLink service environment variables. The following table shows examples of environment variable values:

Environment Variable	Description
<LIBPATH> where <LIBPATH> is: LIBPATH on AIX and z/OS USS LD_LIBRARY_PATH on Solaris and Linux SHLIB_PATH on HP-UX PATH on Windows	Shared library path for the ODBC-to-JDBC bridge and the Java Virtual Machine For example: PATH=D:\Programs\java\j2sdk1.4.2_05\jre\bin\ server;D:\Programs\java\j2sdk1.4.2_05\jre\bin;
CLASSPATH	Classpath containing all JDBC drivers that need to be accessed by the SequeLink Server for JDBC Socket and the classes for the SequeLink for JDBC Socket service For example: CLASSPATH= D:\Programs\DataDirect\slserver60\dev\; D:\Programs\3party\jdbcdriver\driver.jar
ISLVINI	Directory for the license ini file (UNIX only; does not apply on z/OS UNIX System Services) For example: ISLVINI=/usr/sl60/server/ipe
ODBCINI	File with the ODBC configuration information for the ODBC-to-JDBC bridge For example: ODBCINI=/usr/sl60/server/bin/odbc/odbc.ini
SL_JAVA_OPTIONS	Options to influence the Java Virtual Machine used by the backend JDBC driver For example: SL_JAVA_OPTIONS=Xms32m-Xmx64m-Ccomp-verbose

Restart the SequeLink server.
Modify the SequeLink server data source attributes:
DataSourceSOCJDBCConnectionURL. Specify the connection URL.
DataSourceSOCJDBCDriverClassName. Specify the driver class name.
DataSourceSOCJDBCPropertiesName. Specify the database properties name.

Refer to the SequeLink Administrator's Guide for information about using service attributes.

On the SequeLink Client, create a SequeLink data source.
When connecting through the JDBC, .NET, or ODBC Client, no additional configuration tasks are needed.
If you are connecting to SequeLink Server for JDBC Socket through an ADO Client, you must perform additional configuration tasks, as described in the section, "Completing the ODBC Socket Installation for SequeLink for ADO" in the SequeLink Installation Guide. These steps are the same for SequeLink Server for JDBC Socket as they are for the ODBC Socket.

Diagnosing Problems With Backend DataDirect Spy^™ Logs

DataDirect Spy is a development software component that allows you to track JDBC calls.

DataDirect Spy is a software component for tracking JDBC calls at runtime. It passes calls issued by an application to an underlying JDBC driver and logs detailed information about those calls. DataDirect Spy provides the following advantages:

Logging is JDBC 3.0-compliant, including support for the JDBC 2.0 Optional Package.
Logging is consistent, regardless of the JDBC driver used.
All parameters and function results for JDBC calls can be logged.
Logging can be enabled without changing the application.
DataDirect Spy can only be used with the SequeLink for JDBC Driver and the DataDirect Connect^® for JDBC drivers.

When you enable DataDirect Spy for a connection, you can customize DataDirect Spy logging for your needs by setting one or multiple options for DataDirect Spy. For example, you may want to direct logging to a local file on your machine.

To set up a DataDirect Spy log with the SequeLink Server for JDBC Socket, add the key-value pair spy_log=Spy log specification to the DataSourceSOCJDBCConnectionURL to include the DataDirect Spy driver as follows:

DataSourceSOCJDBCConnectionURL=DataSourceSOCJDBCConURL;spy_log=(file)filename 

For example:

DataSourceConnectionURL= 
jdbc:dd-crossaccess30:EXIMS:tcp/10.30.14.109/9001:CODEPAGE=USS};
spy_log=(file)/tmp/spy.log 

Other DataDirect Spy options can be specified by adding key-value pairs in which the original Spy-option name is prefixed with spy_. For example:

DataSourceConnectionURL= 
jdbc:dd-crossaccess30:EXIMS:tcp/10.30.14.109/9001:CODEPAGE=USS;
spy_log= (file)/tmp/spy.log;spy_timestamp=yes 

Using the JDBC Socket Service with the Apache Derby Driver

When you use SequeLink Server for JDBC Socket with the Apache Derby driver, you must specify the classpath and required options for the Apache Derby driver in the SequeLink Service Environment variables. For example:

CLASSPATH=C:\Program Files\IBM\Derby\lib\db2jcc.jar;C:\Program 
Files\DataDirect\slserver60\bin\classes 
SL_JAVA_OPTIONS=-Dderby.system.home=C:\derby\dbsales 

In the data source settings, specify the classpath, the connection URL, the driver name, and the database properties name that will be accessed through the connection.

DataSourceSOCJDBCConnectionURL "jdbc:dd-derby10:dbsales;" 
DataSourceSOCJDBCDriverClassName = com.ddtek.jdbc.derby10.DerbyDriver 
DataSourceSOCJDBCDbPropertiesName = derby  

Save your settings and stop the server. Then, restart the server.

Analyzing JDBC Socket Service Problems

This section explains how to investigate problems or unexpected behavior when using SequeLink Server for JDBC Socket.

Remember that the problem or unexpected behavior could be caused by either SequeLink Server for JDBC Socket or a third-party JDBC driver. Identifying which component is generating the problem is key to solving it.

Identifying Connection Problems

It is important to know the connection information used on a call by SequeLink to initiate the connection to the JDBC driver. When experiencing problems with establishing a connection, examine the values of the following service attributes:

DatasourceSOCJDBCConnectionURL. Check the connection URL.
DataSourceSOCJDBCDriverClassName. Check the Driver Class Name.
DataSourceSOCJDBCDbPropertiesName. Check the properties name.

In addition, examine the values defined for the LIBPATH and CLASSPATH environment variables.

Once you have validated the connection URL and service attributes, SequeLink Server for JDBC Socket should be able to use it to connect successfully to the database.

Identifying the Source of the Problem

To check which component is the source of the problem:

Use the JDBC driver directly. Use the connection URL configured in the DataSourceSOCJDBCConnectionURL service attribute to initiate a direct connection to the JDBC driver.
Use a different JDBC driver to see if the same error occurs. Try using another JDBC driver with SequeLink Server for JDBC Socket and see whether the problem still occurs.
Use JDBC Tracing with DataDirect Spy to investigate problems. SequeLink Server for JDBC Socket comes with the DataDirect Spy tool. You can use this tool to analyze and investigate problems or unexpected behavior. See "DataDirect Spy™" for more information.

Checking the Third-Party Driver Environment

The SequeLink administrator can check the third-party JDBC driver environment that will be used behind the SequeLink Server for JDBC Socket using the ivcheckjdbcdriver utility.

The ivcheckjdbcdriver utility is included in the installation package:

Windows: The bat script ivcheckjdbcdriver.bat is located in the directory where the installer resides.
UNIX: After the untar of the install package, the shell script ivcheckjdbcdriver.sh is located in the directory where the installer resides.

Use this utility before configuring the SequeLink Server for JDBC Socket. You must enter the following configuration information:

The JRE installation directory
The JDBC Driver classpath
The driver classname
The connection URL of your backend JDBC driver

When the ivcheckjdbcdriver script has verified these settings and successfully made a connection, use these settings for the configuration of your SequeLink Server for JDBC Socket. Read the note for specific driver issues.

Example on UNIX:

# ./ivcheckjdbcdriver.sh                                                      
Enter the full path of the directory where the Java Runtime Environment(JRE)                     
is installed                                                                                     
/usr/java/jdk1.5.0_02/jre                                                                        
                                                                         
your JRE installation directory '/usr/java/jdk1.5.0_02/jre' is validated.                        
                                                                  
Enter the CLASSPATH for the back-end JDBC drivers you want to use                                
/sqlnkdev/releases/ext_remote/JDBCDriversForSocket/07/Drivers.jar                                
                              
Enter the driver classname : com.ddtek.jdbc.sequelink.SequeLinkDriver                            
Enter the connection url : jdbc:sequelink://prodsales:15233;serverDataSource=
salesdb               
Enter the user name : sales1                                                                       
Enter the password : ****** 
Driver class was found                                                                           
                                                 
The following drivers are loaded:                                                                
com.ddtek.jdbc.sequelink.SequeLinkDriver                                                         
                                                        
connected                                                                                        
                                      
DatabaseMetaData.getUserName() = sales1                                                            
DatabaseMetaData.getDriverVersion() = 6.0.0056                                                   
DatabaseMetaData.getDatabaseProductName() = DB2/NT                                               
Connection.getCatalog() = null                                                                   
  
Succesfully verified:                                                                            
Driver classname: com.ddtek.jdbc.sequelink.SequeLinkDriver                                       
Connection url: jdbc:sequelink://prodsales:15233;serverDataSource=salesdb 
JRE installation directory : /usr/java/jdk1.5.0_02/jre 
JDBC Driver CLASSPATH      : 
/sqlnkdev/releases/ext_remote/JDBCDriversForSocket/07/Drivers.jar 
============================================================== 
Important note: 
============================================================== 
This utility has checked your third-party JDBC driver. For some drivers, 
SequeLink provides a wrapper driver with its own Driver name and Connection 
url. This wrapper driver fixes incorrect JDBC behavior, provides workarounds 
for driver deficiencies and optimizes code paths. 
For the following third-party drivers we strongly advise using these 
wrappers: 
------------------------------------------------------------ 
Websphere Information Integrator Classic Federation for z/OS 
(also known as CrossAccess or DB2 II Classic Federation) 
------------------------------------------------------------ 
Driver name: com.ddtek.jdbc.crossaccess30.CrossAccessDriver 
Connection url: jdbc:dd-crossaccess30:<datasource>:tcp/<host>/<port> 
-------------------------- 
Apache Derby 10 
(also known as Cloudscape) 
-------------------------- 
Driver name: com.ddtek.jdbc.derby10.DerbyDriver 
Connection url: jdbc:dd-derby10 
end of note 

Example on z/OS USS

# ./ivcheckjdbcdriver.sh 
Enter the full path of the directory where the Java Runtime Environment(JRE) 
is installed 
/usr/lpp/java14/J1.4 
your JRE installation directory '/usr/lpp/java14/J1.4' is validated. 
Enter the CLASSPATH for the back-end JDBC drivers you want to use 
/sqlnkdev/releases/ext/JDBCDriversForSocket/07/Drivers.jar 
Enter the driver classname : com.cac.jdbc.Driver 
Enter the connection url : jdbc:cac:EXIMS:tcp/10.30.14.109/9001:CODEPAGE=USS 
Enter the user name : sales1 
Enter the password : ******** 
Driver class was found 
The following drivers are loaded: 
com.cac.jdbc.Driver 
connected 
DatabaseMetaData.getUserName() = sales1 
DatabaseMetaData.getDriverVersion() = 2.2 
DatabaseMetaData.getDatabaseProductName() = XDI Databases 
Connection.getCatalog() = null 
Succesfully verified: 
Driver classname: com.cac.jdbc.Driver 
Connection url: jdbc:cac:EXIMS:tcp/10.30.14.109/9001:CODEPAGE=USS 
JRE installation directory : /usr/lpp/java14/J1.4 
JDBC Driver CLASSPATH      : 
/sqlnkdev/releases/ext/JDBCDriversForSocket/07/Drivers.jar 
============================================================== 
Important note: 
============================================================== 
This utility has checked your third-party JDBC driver. For some drivers, 
SequeLink provides a wrapper driver with it's own Driver name and Connection 
url. This wrapper driver fixes incorrect JDBC behavior, provides workarounds 
for driver deficiencies and optimizes code paths. 
For the following third-party drivers we strongly advise to use these 
wrappers: 
------------------------------------------------------------ 
Websphere Information Integrator Classic Federation for z/OS 
(also known as CrossAccess or DB2 II Classic Federation) 
------------------------------------------------------------ 
Driver name: com.ddtek.jdbc.crossaccess30.CrossAccessDriver 
Connection url: 
jdbc:dd-crossaccess30:<datasource>:tcp/<host>/<port>:CODEPAGE=USS 
-------------------------- 
Apache Derby 10 
(also known as Cloudscape) 
-------------------------- 
Driver name: com.ddtek.jdbc.derby10.DerbyDriver 
Connection url: jdbc:dd-derby10 
end of note 

Checking the Third-Party JDBC Driver

If configuration problems occur, the SequeLink administrator can use the ivcheckjdbcdriver utility, as described in "Checking the Third-Party Driver Environment". This utility checks the third-party JDBC driver as if it had been called from the SequeLink Server for JDBC Socket.

To use the ivcheckjebc utility to test the Driver classname and the Connection URL that you want to use, do the following:

Set the path environment variable for your specific platform.
Set the classpath environment variable.
Run the script. When prompted, enter the Driver classname and the Connection URL.

If this script runs successfully, you can use the returned Driver classname and the Connection URL for configuring your Sequelink Server for JDBC Socket.

Example:

#./ivcheckjdbc.sh 
Enter the driver classname : com.ddtek.jdbc.sequelink.SequeLinkDriver            
Enter the connection url : jdbc:sequelink://prodsales:15033;serverDataSource=
sales;databaseName=salesdb                                                             
Enter the user name : sales1                                                       
Enter the password : ******                                                    
                     
Driver class was found                                                           
                             
The following drivers are loaded:                                                
com.ddtek.jdbc.sequelink.SequeLinkDriver                                         
                                                                                 
connected                                                                        
                                 
DatabaseMetaData.getUserName() = sales1                                            
DatabaseMetaData.getDriverVersion() = 6.0.0057                                   
DatabaseMetaData.getDatabaseProductName() = DB2/NT                               
Connection.getCatalog() = null                                                   
                                           
Succesfully verified:                                                            
Driver classname: com.ddtek.jdbc.sequelink.SequeLinkDriver                       
Connection url: jdbc:sequelink://prodsales:15033;serverDataSource=
sales;databaseName=salesdb 

Reporting a Problem

DataDirect Technologies technical support may ask you to provide a debug log file. SequeLink Server uses the following types of debug log files:

Session debug log file contains information related to all server processing in the context of a client session. See "SequeLink® Server Session Debug Log File" for more information.
Service debug log file contains information related to service-related processing-any kind of processing that occurs outside the context of a client session. See "SequeLink® Service Debug Log File" for more information.
Server ODBC trace of the backend ODBC-to-JDBC bridge. See "Defining a Server ODBC Trace for the Backend Driver" for more information.
DataDirect Spy logs of the backend JDBC driver.

Connecting with SequeLink^® Server for DB2 on z/OS

This section provides specific information for troubleshooting problems with connections with SequeLink Server for DB2.

Releasing Locks Held by Disassociated DB2 Threads

Errors can occur when a transaction branch becomes disassociated from the thread of control. This can cause problems with locks that are held by disassociated DB2 threads.

An XA transaction branch starts with xa_start() to register a new transaction branch with the resource manager, and ends with xa_end when the application completes a portion of its work, either partially or in its entirety. When xa_end() is successfully returned, the calling thread of control is no longer actively associated with the branch, but the branch still exists. The transaction manager then calls xa_prepare() to request a resource manager to prepare the work performed in that transaction branch for commitment.

During the time between the xa_end() and the xa_prepare(), the transaction branch, represented by an RRS context, is no longer associated with the thread of control. This disassociated RRS context can hold resources in the resource manager on behalf of the transaction branch. The unit of recovery state for this transaction branch is called "InFlight".

After xa_prepare is successfully returned, the transaction branch, represented by an RRS context, is disassociated from the thread of control. This disassociated RRS context can hold resources in the resource manager on behalf of the transaction branch. The unit of recovery state for this transaction branch is called "InDoubt".

The application calls:

xa_commit() to direct the resource manager to commit the transaction branch. The resource manager applies any changes (commits) it has made to shared resources and releases any resources held on behalf of the branch.
xa_rollback() to direct the resource manager to roll back a branch. The resource manager cancels any changes (rolls back) that it applied to shared resources, and releases any resources it held.

Disassociated RRS contexts can be rolled back or committed using the XA RELEASE operator command. For information on using SequeLink Operator Commands, refer to the SequeLink Administrator's Guide.

Disassociated RRS contexts can also be rolled back or committed by using RRS panels.

Log Messages on z/OS

Some log messages are platform-specific, such as the log messages for DB2 UDB on z/OS. This type of message is generated by a Service Task, and begins with a service name and, in some cases, a thread ID. The message continues with a specific error code and message. See "Error Messages" for the details about the error code.

The following examples show the general format of this type of log message:

Tnnnnnnn-ServiceName@Hostname>,ErrorCode=<xxxx>, ErrorMessage=<tttttttttt>.
	Severity:	The severity depends on the situation.
	Explanation:	The explanation of the failure depends on the exact nature of the failure.
	System action:	The system action depends on the exact nature of the failure.
	User response:	The user response depends on the exact nature of the failure.
<service name>@<hostname>,ErrorCode=<xxxx>, ErrorMessage=<text>.
	Severity:	The severity depends on the situation.
	Explanation:	This is a general error message.
	System action:	The operation fails.
	User response:	The user response depends on the exact nature of the failure.

Reporting a Problem

DataDirect Technologies technical support may ask you to provide a debug log file. SequeLink Server uses the following types of debug log files:

Session debug log file contains information related to all server processing in the context of a client session. See "SequeLink® Server Session Debug Log File", for more information.
Service debug log file contains information related to service-related processing-any kind of processing that occurs outside the context of a client session. See "SequeLink® Service Debug Log File" for more information.
Server ODBC trace of the backend driver. See "Defining a Server ODBC Trace for the Backend Driver" for more information.